home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / perl5 / XML / LibXML.pod < prev    next >
Encoding:
Text File  |  2009-10-07  |  14.6 KB  |  516 lines

  1. =head1 NAME
  2.  
  3. XML::LibXML - Perl Binding for libxml2
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.  
  8.  
  9.   use XML::LibXML;
  10.   my $dom = XML::LibXML->load_xml(string => <<'EOT');
  11.   <some-xml/>
  12.   EOT
  13.  
  14.   $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
  15.   $Version_ID = XML::LibXML::LIBXML_VERSION;
  16.   $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
  17.   $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
  18.   $gdomenode = XML::LibXML->export_GDOME( $node, $deep );
  19.  
  20. =head1 DESCRIPTION
  21.  
  22. This module is an interface to libxml2, providing XML and HTML parsers with
  23. DOM, SAX and XMLReader interfaces, a large subset of DOM Layer 3 interface and
  24. a XML::XPath-like interface to XPath API of libxml2. The module is split into
  25. several packages which are not described in this section; unless stated
  26. otherwise, you only need to C<<<<<< use XML::LibXML; >>>>>> in your programs.
  27.  
  28. For further information, please check the following documentation:
  29.  
  30. =over 4
  31.  
  32. =item L<<<<<< XML::LibXML::Parser >>>>>>
  33.  
  34. Parsing XML files with XML::LibXML
  35.  
  36.  
  37. =item L<<<<<< XML::LibXML::DOM >>>>>>
  38.  
  39. XML::LibXML Document Object Model (DOM) Implementation
  40.  
  41.  
  42. =item L<<<<<< XML::LibXML::SAX >>>>>>
  43.  
  44. XML::LibXML direct SAX parser
  45.  
  46.  
  47. =item L<<<<<< XML::LibXML::Reader >>>>>>
  48.  
  49. Reading XML with a pull-parser
  50.  
  51.  
  52. =item L<<<<<< XML::LibXML::Dtd >>>>>>
  53.  
  54. XML::LibXML frontend for DTD validation
  55.  
  56.  
  57. =item L<<<<<< XML::LibXML::RelaxNG >>>>>>
  58.  
  59. XML::LibXML frontend for RelaxNG schema validation
  60.  
  61.  
  62. =item L<<<<<< XML::LibXML::Schema >>>>>>
  63.  
  64. XML::LibXML frontend for W3C Schema schema validation
  65.  
  66.  
  67. =item L<<<<<< XML::LibXML::XPathContext >>>>>>
  68.  
  69. API for evaluating XPath expressions with enhanced support for the evaluation
  70. context
  71.  
  72.  
  73. =item L<<<<<< XML::LibXML::InputCallback >>>>>>
  74.  
  75. Implementing custom URI Resolver and input callbacks
  76.  
  77.  
  78. =item L<<<<<< XML::LibXML::Common >>>>>>
  79.  
  80. Common functions for XML::LibXML related Classes
  81.  
  82.  
  83.  
  84. =back
  85.  
  86. The nodes in the Document Object Model (DOM) are represented by the following
  87. classes (most of which "inherit" from L<<<<<< XML::LibXML::Node >>>>>>):
  88.  
  89. =over 4
  90.  
  91. =item L<<<<<< XML::LibXML::Document >>>>>>
  92.  
  93. XML::LibXML class for DOM document nodes
  94.  
  95.  
  96. =item L<<<<<< XML::LibXML::Node >>>>>>
  97.  
  98. Abstract base class for XML::LibXML DOM nodes
  99.  
  100.  
  101. =item L<<<<<< XML::LibXML::Element >>>>>>
  102.  
  103. XML::LibXML class for DOM element nodes
  104.  
  105.  
  106. =item L<<<<<< XML::LibXML::Text >>>>>>
  107.  
  108. XML::LibXML class for DOM text nodes
  109.  
  110.  
  111. =item L<<<<<< XML::LibXML::Comment >>>>>>
  112.  
  113. XML::LibXML class for comment DOM nodes
  114.  
  115.  
  116. =item L<<<<<< XML::LibXML::CDATASection >>>>>>
  117.  
  118. XML::LibXML class for DOM CDATA sections
  119.  
  120.  
  121. =item L<<<<<< XML::LibXML::Attr >>>>>>
  122.  
  123. XML::LibXML DOM attribute class
  124.  
  125.  
  126. =item L<<<<<< XML::LibXML::DocumentFragment >>>>>>
  127.  
  128. XML::LibXML's DOM L2 Document Fragment implementation
  129.  
  130.  
  131. =item L<<<<<< XML::LibXML::Namespace >>>>>>
  132.  
  133. XML::LibXML DOM namespace nodes
  134.  
  135.  
  136. =item L<<<<<< XML::LibXML::PI >>>>>>
  137.  
  138. XML::LibXML DOM processing instruction nodes
  139.  
  140.  
  141.  
  142. =back
  143.  
  144.  
  145. =head1 ENCODINGS SUPPORT IN XML::LIBXML
  146.  
  147. Recall that since version 5.6.1, Perl distinguishes between character strings
  148. (internally encoded in UTF-8) and so called binary data and, accordingly,
  149. applies either character or byte semantics to them. A scalar representing a
  150. character string is distinguished from a byte string by special flag (UTF8).
  151. Please refer to I<<<<<< perlunicode >>>>>> for details. 
  152.  
  153. XML::LibXML's API is designed to deal with many encodings of XML documents
  154. completely transparently, so that the application using XML::LibXML can be
  155. completely ignorant about the encoding of the XML documents it works with. On
  156. the other hand, functions like C<<<<<< XML::LibXML::Document->setEncoding >>>>>> give the user control over the document encoding. 
  157.  
  158. To ensure the aforementioned transparency and uniformity, most functions of
  159. XML::LibXML that work with in-memory trees accept and return data as character
  160. strings (i.e. UTF-8 encoded with the UTF8 flag on) regardless of the original
  161. document encoding; however, the functions related to I/O operations (i.e.
  162. parsing and saving) operate with binary data (in the original document
  163. encoding) obeying the encoding declaration of the XML documents.
  164.  
  165. Below we summarize basic rules and principles regarding encoding: 
  166.  
  167.  
  168. =over 4
  169.  
  170. =item 1.
  171.  
  172. Do NOT apply any encoding-related PerlIO layers (C<<<<<< :utf8 >>>>>> or C<<<<<< :encoding(...) >>>>>>) to file handles that are an input for the parses or an output for a
  173. serializer of (full) XML documents. This is because the conversion of the data
  174. to/from the internal character representation is provided by libxml2 itself
  175. which must be able to enforce the encoding specified by the C<<<<<< <?xml version="1.0" encoding="..."?> >>>>>> declaration. Here is an example to follow: 
  176.  
  177.   use XML::LibXML;
  178.   open my $fh, "file.xml";
  179.   binmode $fh; # drop all PerlIO layers possibly created by a use open pragma
  180.   $doc = XML::LibXML->load_xml(IO => $fh);
  181.   open my $out, "out.xml";
  182.   binmode $fh; # as above
  183.   $doc->toFh($fh);
  184.   # or
  185.   print $fh $doc->toString();
  186.  
  187.  
  188.  
  189.  
  190.  
  191. =item 2.
  192.  
  193. All functions working with DOM accept and return character strings (UTF-8
  194. encoded with UTF8 flag on). E.g. 
  195.  
  196.   my $doc = XML::LibXML:Document->new('1.0',$some_encoding);
  197.   my $element = $doc->createElement($name);
  198.   $element->appendText($text);
  199.   $xml_fragment = $element->toString(); # returns a character string
  200.   $xml_document = $doc->toString(); # returns a byte string
  201.  
  202. where C<<<<<< $some_encoding >>>>>> is the document encoding that will be used when saving the document, and C<<<<<< $name >>>>>> and C<<<<<< $text >>>>>> contain character strings (UTF-8 encoded with UTF8 flag on). Note that the
  203. method C<<<<<< toString >>>>>> returns XML as a character string if applied to other node than the Document
  204. node and a byte string containing the apropriate 
  205.  
  206.   <?xml version="1.0" encoding="..."?>
  207.  
  208. declaration if applied to a L<<<<<< XML::LibXML::Document >>>>>>. 
  209.  
  210.  
  211.  
  212. =item 3.
  213.  
  214. DOM methods also accept binary strings in the original encoding of the document
  215. to which the node belongs (UTF-8 is assumed if the node is not attached to any
  216. document). Exploiting this feature is NOT RECOMMENDED since it is considered a
  217. bad practice. 
  218.  
  219.  
  220.  
  221.   my $doc = XML::LibXML:Document->new('1.0','iso-8859-2');
  222.   my $text = $doc->createTextNode($some_latin2_encoded_byte_string);
  223.   # WORKS, BUT NOT RECOMMENDED!
  224.  
  225.  
  226.  
  227. =back
  228.  
  229. I<<<<<< NOTE: >>>>>> libxml2 support for many encodings is based on the iconv library. The actual
  230. list of supported encodings may vary from platform to platform. To test if your
  231. platform works correctly with your language encoding, build a simple document
  232. in the particular encoding and try to parse it with XML::LibXML to see if the
  233. parser produces any errors. Occasional crashes were reported on rare platforms
  234. that ship with a broken version of iconv.
  235.  
  236.  
  237. =head1 THREAD SUPPORT
  238.  
  239. XML::LibXML since 1.67 partially supports Perl threads in Perl >= 5.8.8.
  240. XML::LibXML can be used with threads in two ways: 
  241.  
  242. By default, all XML::LibXML classes use CLONE_SKIP class method to prevent Perl
  243. from copying XML::LibXML::* objects when a new thread is spawn. In this mode,
  244. all XML::LibXML::* objects are thread specific. This is the safest way to work
  245. with XML::LibXML in threads. 
  246.  
  247. Alternatively, one may use 
  248.  
  249.  
  250.  
  251.   use threads;
  252.   use XML::LibXML qw(:threads_shared);
  253.  
  254. to indicate, that all XML::LibXML node and parser objects should be shared
  255. between the main thread and any thread spawn from there. For example, in 
  256.  
  257.  
  258.  
  259.   my $doc = XML::LibXML->load_xml(location => $filename);
  260.   my $thr = threads->new(sub{
  261.     # code working with $doc
  262.     1;
  263.   });
  264.   $thr->join;
  265.  
  266. the variable C<<<<<< $doc >>>>>> refers to the exact same XML::LibXML::Document in the spawned thread as in the
  267. main thread. 
  268.  
  269. Without using mutex locks, oaralel threads may read the same document (i.e. any
  270. node that belongs to the document), parse files, and modify different
  271. documents. 
  272.  
  273. However, if there is a chance that some of the threads will attempt to modify a
  274. document ( or even create new nodes based on that document, e.g. with C<<<<<< $doc->createElement >>>>>>) that other threads may be reading at the same time, the user is responsible
  275. for creating a mutex lock and using it in I<<<<<< both >>>>>> in the thread that modifies and the thread that reads: 
  276.  
  277.  
  278.  
  279.   my $doc = XML::LibXML->load_xml(location => $filename);
  280.   my $mutex : shared;
  281.   my $thr = threads->new(sub{
  282.      lock $mutex;
  283.      my $el = $doc->createElement('foo');
  284.      # ...
  285.     1;
  286.   });
  287.   { 
  288.     lock $mutex;
  289.     my $root = $doc->documentElement;
  290.     say $root->name;
  291.   }
  292.   $thr->join;
  293.  
  294. Note that libxml2 uses dictionaries to store short strings and these
  295. dicionaries are kept on a document node. Without mutex locks, it could happen
  296. in the previous example that the thread modifies the dictionary while other
  297. threads attempt to read from it, which could easily lead to a crash.
  298.  
  299.  
  300. =head1 VERSION INFORMATION
  301.  
  302. Sometimes it is useful to figure out, for which version XML::LibXML was
  303. compiled for. In most cases this is for debugging or to check if a given
  304. installation meets all functionality for the package. The functions
  305. XML::LibXML::LIBXML_DOTTED_VERSION and XML::LibXML::LIBXML_VERSION provide this
  306. version information. Both functions simply pass through the values of the
  307. similar named macros of libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION
  308. returns the version of the (usually dynamically) linked libxml2. 
  309.  
  310. =over 4
  311.  
  312. =item XML::LibXML::LIBXML_DOTTED_VERSION
  313.  
  314.   $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
  315.  
  316. Returns the version string of the libxml2 version XML::LibXML was compiled for.
  317. This will be "2.6.2" for "libxml2 2.6.2".
  318.  
  319.  
  320. =item XML::LibXML::LIBXML_VERSION
  321.  
  322.   $Version_ID = XML::LibXML::LIBXML_VERSION;
  323.  
  324. Returns the version id of the libxml2 version XML::LibXML was compiled for.
  325. This will be "20602" for "libxml2 2.6.2". Don't mix this version id with
  326. $XML::LibXML::VERSION. The latter contains the version of XML::LibXML itself
  327. while the first contains the version of libxml2 XML::LibXML was compiled for.
  328.  
  329.  
  330. =item XML::LibXML::LIBXML_RUNTIME_VERSION
  331.  
  332.   $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
  333.  
  334. Returns a version string of the libxml2 which is (usually dynamically) linked
  335. by XML::LibXML. This will be "20602" for libxml2 released as "2.6.2" and
  336. something like "20602-CVS2032" for a CVS build of libxml2.
  337.  
  338. XML::LibXML issues a warning if the version of libxml2 dynamically linked to it
  339. is less than the version of libxml2 which it was compiled against. 
  340.  
  341.  
  342.  
  343. =back
  344.  
  345.  
  346. =head1 EXPORTS
  347.  
  348. By default the module exports all constants and functions listed in the :all
  349. tag, described below. 
  350.  
  351.  
  352. =head1 EXPORT TAGS
  353.  
  354. =over 4
  355.  
  356. =item C<<<<<< :all >>>>>>
  357.  
  358. Includes the tags C<<<<<< :libxml >>>>>>, C<<<<<< :encoding >>>>>>, and C<<<<<< :ns >>>>>> described below.
  359.  
  360.  
  361. =item C<<<<<< :libxml >>>>>>
  362.  
  363. Exports integer constants for DOM node types.
  364.  
  365.  
  366.  
  367.   XML_ELEMENT_NODE            => 1
  368.   XML_ATTRIBUTE_NODE          => 2
  369.   XML_TEXT_NODE               => 3
  370.   XML_CDATA_SECTION_NODE      => 4
  371.   XML_ENTITY_REF_NODE         => 5
  372.   XML_ENTITY_NODE             => 6
  373.   XML_PI_NODE                 => 7
  374.   XML_COMMENT_NODE            => 8
  375.   XML_DOCUMENT_NODE           => 9
  376.   XML_DOCUMENT_TYPE_NODE      => 10
  377.   XML_DOCUMENT_FRAG_NODE      => 11
  378.   XML_NOTATION_NODE           => 12
  379.   XML_HTML_DOCUMENT_NODE      => 13
  380.   XML_DTD_NODE                => 14
  381.   XML_ELEMENT_DECL            => 15
  382.   XML_ATTRIBUTE_DECL          => 16
  383.   XML_ENTITY_DECL             => 17
  384.   XML_NAMESPACE_DECL          => 18
  385.   XML_XINCLUDE_START          => 19
  386.   XML_XINCLUDE_END            => 20
  387.  
  388.  
  389. =item C<<<<<< :encoding >>>>>>
  390.  
  391. Exports two encoding conversion functions from XML::LibXML::Common.
  392.  
  393.  
  394.  
  395.   encodeToUTF8()
  396.   decodeFromUTF8()
  397.  
  398.  
  399. =item C<<<<<< :ns >>>>>>
  400.  
  401. Exports two convenience constants: the implicit namespace of the reserved C<<<<<< xml: >>>>>> prefix, and the implicit namespace for the reserved C<<<<<< xmlns: >>>>>> prefix.
  402.  
  403.  
  404.  
  405.   XML_XML_NS    => 'http://www.w3.org/XML/1998/namespace'
  406.   XML_XMLNS_NS  => 'http://www.w3.org/2000/xmlns/'
  407.  
  408.  
  409.  
  410. =back
  411.  
  412.  
  413. =head1 RELATED MODULES
  414.  
  415. The modules described in this section are not part of the XML::LibXML package
  416. itself. As they support some additional features, they are mentioned here.
  417.  
  418. =over 4
  419.  
  420. =item L<<<<<< XML::LibXSLT >>>>>>
  421.  
  422. XSLT 1.0 Processor using libxslt and XML::LibXML
  423.  
  424.  
  425. =item L<<<<<< XML::LibXML::Iterator >>>>>>
  426.  
  427. XML::LibXML Implementation of the DOM Traversal Specification
  428.  
  429.  
  430. =item L<<<<<< XML::CompactTree::XS >>>>>>
  431.  
  432. Uses XML::LibXML::Reader to very efficiently to parse XML document or element
  433. into native Perl data structures, which are less flexible but significantly
  434. faster to process then DOM.
  435.  
  436.  
  437.  
  438. =back
  439.  
  440.  
  441. =head1 XML::LIBXML AND XML::GDOME
  442.  
  443. Note: I<<<<<< THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL >>>>>>
  444.  
  445. Although both modules make use of libxml2's XML capabilities, the DOM
  446. implementation of both modules are not compatible. But still it is possible to
  447. exchange nodes from one DOM to the other. The concept of this exchange is
  448. pretty similar to the function cloneNode(): The particular node is copied on
  449. the low-level to the opposite DOM implementation.
  450.  
  451. Since the DOM implementations cannot coexist within one document, one is forced
  452. to copy each node that should be used. Because you are always keeping two nodes
  453. this may cause quite an impact on a machines memory usage.
  454.  
  455. XML::LibXML provides two functions to export or import GDOME nodes:
  456. import_GDOME() and export_GDOME(). Both function have two parameters: the node
  457. and a flag for recursive import. The flag works as in cloneNode().
  458.  
  459. The two functions allow to export and import XML::GDOME nodes explicitly,
  460. however, XML::LibXML allows also the transparent import of XML::GDOME nodes in
  461. functions such as appendChild(), insertAfter() and so on. While native nodes
  462. are automatically adopted in most functions XML::GDOME nodes are always cloned
  463. in advance. Thus if the original node is modified after the operation, the node
  464. in the XML::LibXML document will not have this information.
  465.  
  466. =over 4
  467.  
  468. =item import_GDOME
  469.  
  470.   $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
  471.  
  472. This clones an XML::GDOME node to a XML::LibXML node explicitly.
  473.  
  474.  
  475. =item export_GDOME
  476.  
  477.   $gdomenode = XML::LibXML->export_GDOME( $node, $deep );
  478.  
  479. Allows to clone an XML::LibXML node into a XML::GDOME node.
  480.  
  481.  
  482.  
  483. =back
  484.  
  485.  
  486. =head1 CONTACTS
  487.  
  488. For bug reports, please use the CPAN request tracker on
  489. http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML
  490.  
  491. For suggestions etc., and other issues related to XML::LibXML you may use the
  492. perl XML mailing list (C<<<<<< perl-xml@listserv.ActiveState.com >>>>>>), where most XML-related Perl modules are discussed. In case of problems you
  493. should check the archives of that list first. Many problems are already
  494. discussed there. You can find the list's archives and subscription options at L<<<<<< http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml >>>>>>. 
  495.  
  496. =head1 AUTHORS
  497.  
  498. Matt Sergeant, 
  499. Christian Glahn, 
  500. Petr Pajas
  501.  
  502.  
  503. =head1 VERSION
  504.  
  505. 1.70
  506.  
  507. =head1 COPYRIGHT
  508.  
  509. 2001-2007, AxKit.com Ltd.
  510.  
  511. 2002-2006, Christian Glahn.
  512.  
  513. 2006-2009, Petr Pajas.
  514.  
  515. =cut
  516.